PROLOG¶

This manual page is part of the POSIX Programmer's Manual. The Linux implementation of this interface may differ (consult the corresponding Linux manual page for details of Linux behavior), or the interface may not be implemented on Linux.

NAME¶

patch — apply changes to files

SYNOPSIS¶

patch [−blNR] [−c|−e|−n|−u] [−d dir] [−D define] [−i patchfile]


    [−o outfile] [−p num] [−r rejectfile] [file]

DESCRIPTION¶

The patch utility shall read a source (patch) file containing any of four forms of difference (diff) listings produced by the diff utility (normal, copied context, unified context, or in the style of ed) and apply those differences to a file. By default, patch shall read from the standard input.

The patch utility shall attempt to determine the type of the diff listing, unless overruled by a −c, −e, −n, or −u option.

If the patch file contains more than one patch, patch shall attempt to apply each of them as if they came from separate patch files. (In this case, the application shall ensure that the name of the patch file is determinable for each diff listing.)

OPTIONS¶

The patch utility shall conform to the Base Definitions volume of POSIX.1‐2008, Section 12.2, Utility Syntax Guidelines.

The following options shall be supported:

−b

Save a copy of the original contents of each modified file, before the differences are applied, in a file of the same name with the suffix .orig appended to it. If the file already exists, it shall be overwritten; if multiple patches are applied to the same file, the .orig file shall be written only for the first patch. When the −o outfile option is also specified, file.orig shall not be created but, if outfile already exists, outfile.orig shall be created.

−c

Interpret the patch file as a copied context difference (the output of the utility diff when the −c or −C options are specified).

−d dir

Change the current directory to dir before processing as described in the EXTENDED DESCRIPTION section.

−D define

Mark changes with one of the following C preprocessor constructs:

#ifdef define
...
#endif

#ifndef define
...
#endif

−e

Interpret the patch file as an ed script, rather than a diff script.

−i patchfile

Read the patch information from the file named by the pathname patchfile, rather than the standard input.

−l

(The letter ell.) Cause any sequence of <blank> characters in the difference script to match any sequence of <blank> characters in the input file. Other characters shall be matched exactly.

−n

Interpret the script as a normal difference.

−N

Ignore patches where the differences have already been applied to the file; by default, already-applied patches shall be rejected.

−o outfile

Instead of modifying the files (specified by the file operand or the difference listings) directly, write a copy of the file referenced by each patch, with the appropriate differences applied, to outfile. Multiple patches for a single file shall be applied to the intermediate versions of the file created by any previous patches, and shall result in multiple, concatenated versions of the file being written to outfile.

−p num

For all pathnames in the patch file that indicate the names of files to be patched, delete num pathname components from the beginning of each pathname. If the pathname in the patch file is absolute, any leading <slash> characters shall be considered the first component (that is, −p 1 shall remove the leading <slash> characters). Specifying −p 0 shall cause the full pathname to be used. If −p is not specified, only the basename (the final pathname component) shall be used.

−R

Reverse the sense of the patch script; that is, assume that the difference script was created from the new version to the old version. The −R option cannot be used with ed scripts. The patch utility shall attempt to reverse each portion of the script before applying it. Rejected differences shall be saved in swapped format. If this option is not specified, and until a portion of the patch file is successfully applied, patch attempts to apply each portion in its reversed sense as well as in its normal sense. If the attempt is successful, the user shall be prompted to determine whether the −R option should be set.

−r rejectfile

Override the default reject filename. In the default case, the reject file shall have the same name as the output file, with the suffix .rej appended to it; see Patch Application.

−u

Interpret the patch file as a unified context difference (the output of the diff utility when the −u or −U options are specified).

OPERANDS¶

The following operand shall be supported:

file

A pathname of a file to patch.

STDIN¶

See the INPUT FILES section.

INPUT FILES¶

Input files shall be text files.

ENVIRONMENT VARIABLES¶

The following environment variables shall affect the execution of patch:

LANG

Provide a default value for the internationalization variables that are unset or null. (See the Base Definitions volume of POSIX.1‐2008, Section 8.2, Internationalization Variables the precedence of internationalization variables used to determine the values of locale categories.)

LC_ALL

If set to a non-empty string value, override the values of all the other internationalization variables.

LC_COLLATE

Determine the locale for the behavior of ranges, equivalence classes, and multi-character collating elements used in the extended regular expression defined for the yesexpr locale keyword in the LC_MESSAGES category.

LC_CTYPE

Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as opposed to multi-byte characters in arguments and input files), and the behavior of character classes used in the extended regular expression defined for the yesexpr locale keyword in the LC_MESSAGES category.

LC_MESSAGES

Determine the locale used to process affirmative responses, and the locale used to affect the format and contents of diagnostic messages and prompts written to standard error.

NLSPATH

Determine the location of message catalogs for the processing of LC_MESSAGES.

LC_TIME

Determine the locale for recognizing the format of file timestamps written by the diff utility in a context-difference input file.

ASYNCHRONOUS EVENTS¶

Default.

STDOUT¶

Not used.

STDERR¶

The standard error shall be used for diagnostic and informational messages.

OUTPUT FILES¶

The output of the patch utility, the save files (.orig suffixes), and the reject files (.rej suffixes) shall be text files.

EXTENDED DESCRIPTION¶

A patch file may contain patching instructions for more than one file; filenames shall be determined as specified in Filename Determination. When the −b option is specified, for each patched file, the original shall be saved in a file of the same name with the suffix .orig appended to it.

For each patched file, a reject file may also be created as noted in Patch Application. In the absence of a −r option, the name of this file shall be formed by appending the suffix .rej to the original filename.

EXIT STATUS¶

The following exit values shall be returned:

 0

Successful completion.

 1

One or more lines were written to a reject file.

>1

An error occurred.

CONSEQUENCES OF ERRORS¶

Patches that cannot be correctly placed in the file shall be written to a reject file.

The following sections are informative.

APPLICATION USAGE¶

The −R option does not work with ed scripts because there is too little information to reconstruct the reverse operation.

The −p option makes it possible to customize a patch file to local user directory structures without manually editing the patch file. For example, if the filename in the patch file was:

/curds/whey/src/blurfl/blurfl.c

Setting −p 0 gives the entire pathname unmodified; −p 1 gives:

curds/whey/src/blurfl/blurfl.c

without the leading <slash>, −p 4 gives:

blurfl/blurfl.c

and not specifying −p at all gives:

blurfl.c .

EXAMPLES¶

None.

RATIONALE¶

Some of the functionality in historical patch implementations was not specified. The following documents those features present in historical implementations that have not been specified.

A deleted piece of functionality was the '+' pseudo-option allowing an additional set of options and a patch file operand to be given. This was seen as being insufficiently useful to standardize.

In historical implementations, if the string "Prereq:" appeared in the header, the patch utility would search for the corresponding version information (the string specified in the header, delimited by <blank> characters or the beginning or end of a line or the file) anywhere in the original file. This was deleted as too simplistic and insufficiently trustworthy a mechanism to standardize. For example, if:

Prereq: 1.2

were in the header, the presence of a delimited 1.2 anywhere in the file would satisfy the prerequisite.

The following options were dropped from historical implementations of patch as insufficiently useful to standardize:

−b

The −b option historically provided a method for changing the name extension of the backup file from the default .orig. This option has been modified and retained in this volume of POSIX.1‐2008.

−F

The −F option specified the number of lines of a context diff to ignore when searching for a place to install a patch.

−f

The −f option historically caused patch not to request additional information from the user.

−r

The −r option historically provided a method of overriding the extension of the reject file from the default .rej.

−s

The −s option historically caused patch to work silently unless an error occurred.

−x

The −x option historically set internal debugging flags.

In some file system implementations, the saving of a .orig file may produce unwanted results. In the case of 12, 13, or 14-character filenames (on file systems supporting 14-character maximum filenames), the .orig file overwrites the new file. The reject file may also exceed this filename limit. It was suggested, due to some historical practice, that a <tilde> ('~') suffix be used instead of .orig and some other character instead of the .rej suffix. This was rejected because it is not obvious to the user which file is which. The suffixes .orig and .rej are clearer and more understandable.

The −b option has the opposite sense in some historical implementations—do not save the .orig file. The default case here is not to save the files, making patch behave more consistently with the other standard utilities.

The −w option in early proposals was changed to −l to match historical practice.

The −N option was included because without it, a non-interactive application cannot reject previously applied patches. For example, if a user is piping the output of diff into the patch utility, and the user only wants to patch a file to a newer version non-interactively, the −N option is required.

Changes to the −l option description were proposed to allow matching across <newline> characters in addition to just <blank> characters. Since this is not historical practice, and since some ambiguities could result, it is suggested that future developments in this area utilize another option letter, such as −L.

The −u option of GNU patch has been added, along with support for unified context formats.

FUTURE DIRECTIONS¶

None.

SEE ALSO¶

diff, ed

The Base Definitions volume of POSIX.1‐2008, Chapter 8, Environment Variables, Section 12.2, Utility Syntax Guidelines

COPYRIGHT¶

Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 7, Copyright (C) 2013 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. (This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the event of any discrepancy between this version and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.unix.org/online.html .

Any typographical or formatting errors that appear in this page are most likely to have been introduced during the conversion of the source files to man page format. To report such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .